<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>

    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta content="Cask Data, Inc." name="author" />
<meta content="Copyright © 2014-2016 Cask Data, Inc." name="copyright" />


    <meta name="git_release" content="6.1.1">
    <meta name="git_hash" content="05fbac36f9f7aadeb44f5728cea35136dbc243e5">
    <meta name="git_timestamp" content="2020-02-09 08:22:47 +0800">
    <title>Transaction System</title>

    <link rel="stylesheet" href="../_static/cdap-bootstrap.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-3.3.6/css/bootstrap.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/bootstrap-sphinx.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/cdap-dynamicscrollspy-4.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/jquery.mCustomScrollbar.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/cdap-jquery.mCustomScrollbar.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/abixTreeList-2.css" type="text/css" />
    <link rel="stylesheet" href="../_static/cdap-bootstrap.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '6.1.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>

    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="top" title="Cask Data Application Platform 6.1.1 Documentation" href="../index.html" />
    <link rel="up" title="核心概念" href="index.html" />
    <link rel="next" title="Transactional Messaging System" href="transactional-messaging-system.html" />
    <link rel="prev" title="Namespaces" href="namespaces.html" />
    <!-- block extrahead -->
    <meta charset='utf-8'>
    <meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
    <meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
    <meta name="apple-mobile-web-app-capable" content="yes">
    <!-- block extrahead end -->

</head>
<body role="document">

<!-- block navbar -->
<div id="navbar" class="navbar navbar-inverse navbar-default navbar-fixed-top">
    <div class="container-fluid">
      <div class="row">
        <div class="navbar-header">
          <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
          <a class="navbar-brand" href="../table-of-contents/../../index.html">
            <span><img alt="CDAP logo" src="../_static/cdap_logo.svg"/></span>
          </a>

          <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
          </button>

          <div class="pull-right">
            <div class="dropdown version-dropdown">
              <a href="#" class="dropdown-toggle" data-toggle="dropdown"
                role="button" aria-haspopup="true" aria-expanded="false">
                v 6.1.1 <span class="caret"></span>
              </a>
              <ul class="dropdown-menu">
                <li><a href="//docs.cdap.io/cdap/5.1.2/en/index.html">v 5.1.2</a></li>
                <li><a href="//docs.cdap.io/cdap/4.3.4/en/index.html">v 4.3.4</a></li>
              </ul>
            </div>
          </div>
          <form class="navbar-form navbar-right navbar-search" action="../search.html" method="get">
            <div class="form-group">
              <div class="navbar-search-image material-icons"></div>
              <input type="text" name="q" class="form-control" placeholder="  Search" />
            </div>
            <input type="hidden" name="check_keywords" value="yes" />
            <input type="hidden" name="area" value="default" />
          </form>

          <div class="collapse navbar-collapse nav-collapse navbar-right navbar-navigation">
            <ul class="nav navbar-nav"><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../index.html">简介</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link current" href="../table-of-contents/../../guides.html">手册</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../reference-manual/index.html">参考</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../faqs/index.html">帮助</a></li>
            </ul>
          </div>

        </div>
      </div>
    </div>
  </div><!-- block navbar end -->
<!-- block main content -->
<div class="main-container container">
  <div class="row"><div class="col-md-2">
      <div id="sidebar" class="bs-sidenav scrollable-y-outside" role="complementary">
<!-- theme_manual: developer-manual -->
<!-- theme_manual_highlight: guides -->
<!-- sidebar_title_link: ../table-of-contents/../../guides.html -->

  <div role="note" aria-label="manuals links"><h3><a href="../table-of-contents/../../guides.html">Guides</a></h3>

    <ul class="this-page-menu">
      <li class="toctree-l1"><a href="../table-of-contents/../../user-guide/index.html" rel="nofollow">用户手册</a>
      </li>
      <li class="toctree-l1"><b><a href="../table-of-contents/../../developer-manual/index.html" rel="nofollow">开发手册</a></b>
      <nav class="pagenav">
      <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html"> 简介</a></li>
<li class="toctree-l1"><a class="reference internal" href="../getting-started/index.html"> 入门指南</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../getting-started/sandbox/index.html">CDAP Sandbox</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../getting-started/sandbox/zip.html">二进制 Zip 文件</a></li>
<li class="toctree-l3"><a class="reference internal" href="../getting-started/sandbox/zip.html#cdap-sandbox">启动和停止 CDAP Sandbox</a></li>
<li class="toctree-l3"><a class="reference internal" href="../getting-started/sandbox/virtual-machine.html">虚拟机镜像</a></li>
<li class="toctree-l3"><a class="reference internal" href="../getting-started/sandbox/docker.html">Docker 镜像</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../getting-started/quick-start.html">快速入门</a></li>
<li class="toctree-l2"><a class="reference internal" href="../getting-started/dev-env.html">搭建开发环境</a></li>
<li class="toctree-l2"><a class="reference internal" href="../getting-started/start-stop-cdap.html">启动和停止 CDAP</a></li>
<li class="toctree-l2"><a class="reference internal" href="../getting-started/building-apps.html">构建并运行应用</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../overview/index.html"> 概述</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../overview/anatomy.html"> 大数据应用剖析</a></li>
<li class="toctree-l2"><a class="reference internal" href="../overview/modes.html"> 模式和组件</a></li>
<li class="toctree-l2"><a class="reference internal" href="../overview/abstractions.html"> 核心概念</a></li>
<li class="toctree-l2"><a class="reference internal" href="../overview/interfaces.html"> 编程接口</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html"> 抽象概念</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="core.html"> Core Abstractions</a></li>
<li class="toctree-l2"><a class="reference internal" href="applications.html"> Applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="datasets/index.html"> Datasets</a><ul>
<li class="toctree-l3"><a class="reference internal" href="datasets/overview.html"> Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="datasets/table.html"> Table API</a></li>
<li class="toctree-l3"><a class="reference internal" href="datasets/fileset.html"> FileSets</a></li>
<li class="toctree-l3"><a class="reference internal" href="datasets/partitioned-fileset.html"> Partitioned FileSets</a></li>
<li class="toctree-l3"><a class="reference internal" href="datasets/time-partitioned-fileset.html"> TimePartitioned FileSets</a></li>
<li class="toctree-l3"><a class="reference internal" href="datasets/system-custom.html"> System and Custom Datasets</a></li>
<li class="toctree-l3"><a class="reference internal" href="datasets/permissions.html"> Dataset Permissions</a></li>
<li class="toctree-l3"><a class="reference internal" href="datasets/cube.html"> Cube Dataset</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="mapreduce-programs.html"> MapReduce Programs</a></li>
<li class="toctree-l2"><a class="reference internal" href="plugins.html"> Plugins</a></li>
<li class="toctree-l2"><a class="reference internal" href="schedules.html"> Schedules</a></li>
<li class="toctree-l2"><a class="reference internal" href="secure-keys.html"> Secure Keys</a></li>
<li class="toctree-l2"><a class="reference internal" href="services.html"> Services</a></li>
<li class="toctree-l2"><a class="reference internal" href="spark-programs.html"> Spark Programs</a></li>
<li class="toctree-l2"><a class="reference internal" href="workers.html"> Workers</a></li>
<li class="toctree-l2"><a class="reference internal" href="workflows.html"> Workflows</a></li>
<li class="toctree-l2"><a class="reference internal" href="artifacts.html"> Artifacts</a></li>
<li class="toctree-l2"><a class="reference internal" href="program-lifecycle.html"> Program Lifecycle</a></li>
<li class="toctree-l2"><a class="reference internal" href="namespaces.html"> Namespaces</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#"> Transaction System</a></li>
<li class="toctree-l2"><a class="reference internal" href="transactional-messaging-system.html"> Transactional Messaging System</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../metadata/index.html"> 元数据</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../metadata/system-metadata.html"> System Metadata</a></li>
<li class="toctree-l2"><a class="reference internal" href="../metadata/discovery-lineage.html"> Discovery and Lineage</a></li>
<li class="toctree-l2"><a class="reference internal" href="../metadata/field-lineage.html"> Field Level Lineage</a></li>
<li class="toctree-l2"><a class="reference internal" href="../metadata/audit-logging.html"> Audit Logging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../metadata/metadata-ui.html"> CDAP Metadata UI</a></li>
<li class="toctree-l2"><a class="reference internal" href="../metadata/programmatic-metadata.html"> Accessing metadata programmatically</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../pipelines/index.html"> 数据流管道</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../pipelines/concepts-design.html"> Concepts and Design</a></li>
<li class="toctree-l2"><a class="reference internal" href="../pipelines/getting-started.html"> Getting Started</a></li>
<li class="toctree-l2"><a class="reference internal" href="../pipelines/studio.html"> CDAP Studio</a></li>
<li class="toctree-l2"><a class="reference internal" href="../pipelines/creating-pipelines.html"> Creating Pipelines</a></li>
<li class="toctree-l2"><a class="reference internal" href="../pipelines/running-pipelines.html"> Running Pipelines</a></li>
<li class="toctree-l2"><a class="reference internal" href="../pipelines/plugin-management.html"> Plugin Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="../pipelines/plugins/index.html"> Plugin Reference</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/plugins/actions/index.html"> Action Plugins</a><ul class="simple">
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/plugins/sources/index.html"> Source Plugins</a><ul class="simple">
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/plugins/transforms/index.html"> Transform Plugins</a><ul class="simple">
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/plugins/analytics/index.html"> Analytic Plugins</a><ul class="simple">
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/plugins/sinks/index.html"> Sink Plugins</a><ul class="simple">
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/plugins/shared-plugins/index.html"> Shared Plugins</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../pipelines/plugins/shared-plugins/core.html">CoreValidator</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/plugins/post-run-plugins/index.html"> Post-run Plugins</a><ul class="simple">
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../pipelines/developing-pipelines.html"> Developing Pipelines</a></li>
<li class="toctree-l2"><a class="reference internal" href="../pipelines/developing-plugins/index.html"> Developing Plugins</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/developing-plugins/plugin-basics.html">Plugin Basics</a></li>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/developing-plugins/creating-a-plugin.html">Creating a Plugin</a></li>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/developing-plugins/presentation-plugins.html">Plugin Presentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/developing-plugins/testing-plugins.html">Testing Plugins</a></li>
<li class="toctree-l3"><a class="reference internal" href="../pipelines/developing-plugins/packaging-plugins.html">Packaging Plugins</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../pipelines/how-cdap-pipelines-work.html"> How CDAP Pipelines Work</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../cloud-runtimes/index.html"> 云平台运行</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../cloud-runtimes/concepts/index.html"> Concepts</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cloud-runtimes/provisioners/index.html"> Provisioners</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../cloud-runtimes/provisioners/gcp-dataproc.html">Google Dataproc</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cloud-runtimes/provisioners/aws-emr.html">Amazon Elastic MapReduce</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cloud-runtimes/provisioners/remote-hadoop.html">Remote Hadoop</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../cloud-runtimes/profiles/index.html"> Profiles</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../cloud-runtimes/profiles/creating-profiles.html">Creating Profiles</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cloud-runtimes/profiles/assigning-profiles.html">Assigning Profiles</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cloud-runtimes/profiles/admin-controls.html">Admin Controls</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../cloud-runtimes/example/index.html"> Example</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../security/index.html"> 安全</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../security/client-authentication.html">Client Authentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="../security/cdap-authentication-clients-java.html">CDAP Authentication Client for Java</a></li>
<li class="toctree-l2"><a class="reference internal" href="../security/cdap-authentication-clients-python.html">CDAP Authentication Client for Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="../security/custom-authentication.html">Custom Authentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="../security/authorization-extensions.html">Authorization Extensions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../testing/index.html"> 测试和调试</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../testing/testing.html"> Testing a CDAP Application</a></li>
<li class="toctree-l2"><a class="reference internal" href="../testing/debugging.html"> Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../testing/troubleshooting.html"> Troubleshooting</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../ingesting-tools/index.html"> 数据融合</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../ingesting-tools/cdap-stream-clients-java.html">CDAP Stream Client for Java</a></li>
<li class="toctree-l2"><a class="reference internal" href="../ingesting-tools/cdap-stream-clients-python.html">CDAP Stream Client for Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="../ingesting-tools/cdap-stream-clients-ruby.html">CDAP Stream Client for Ruby</a></li>
<li class="toctree-l2"><a class="reference internal" href="../ingesting-tools/cdap-flume.html">CDAP Flume</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../data-exploration/index.html"> 数据探索</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../data-exploration/filesets.html"> Fileset Exploration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../data-exploration/tables.html"> Table Exploration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../data-exploration/object-mapped-tables.html"> ObjectMappedTable Exploration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../data-exploration/custom-datasets.html"> Custom Dataset Exploration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../data-exploration/hive-execution-engines.html"> Hive Execution Engines</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/index.html"> 高级主题</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../advanced/application-logback.html"> Application Logback</a></li>
<li class="toctree-l2"><a class="reference internal" href="../advanced/best-practices.html"> Best Practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="../advanced/class-loading.html"> Class Loading</a></li>
<li class="toctree-l2"><a class="reference internal" href="../advanced/configuring-resources.html"> Configuring Program Resources</a></li>
<li class="toctree-l2"><a class="reference internal" href="../advanced/program-retry-policies.html"> Program Retry Policies</a></li>
</ul>
</li>
</ul>
</nav>
      </li>
      <li class="toctree-l1"><a href="../table-of-contents/../../admin-manual/index.html" rel="nofollow">管理手册</a>
      </li>
      <li class="toctree-l1"><a href="../table-of-contents/../../integrations/index.html" rel="nofollow">集成手册</a>
      </li>
      <li class="toctree-l1"><a href="../table-of-contents/../../examples-manual/index.html" rel="nofollow">最佳实践</a>
      </li>
    </ul>
  </div></div>
    </div><div class="col-md-8 content" id="main-content">
    
  <div class="section" id="transaction-system">
<span id="id1"></span><h1>Transaction System<a class="headerlink" href="#transaction-system" title="Permalink to this headline">🔗</a></h1>
<div class="section" id="the-need-for-transactions">
<h2>The Need for Transactions<a class="headerlink" href="#the-need-for-transactions" title="Permalink to this headline">🔗</a></h2>
<p>A flowlet processes the data objects received on its inputs one at a time. While processing
a single input object, all operations, including the removal of the data from the input,
and emission of data to the outputs, are executed in a <em>transaction</em>. This provides us
with ACID—atomicity, consistency, isolation, and durability properties:</p>
<ul class="simple">
<li>The process method runs under read isolation to ensure that it does not see dirty writes
(uncommitted writes from concurrent processing) in any of its reads.
It does see, however, its own writes.</li>
<li>A failed attempt to process an input object leaves the data in a consistent state;
it does not leave partial writes behind.</li>
<li>All writes and emission of data are committed atomically;
either all of them or none of them are persisted.</li>
<li>After processing completes successfully, all its writes are persisted in a durable way.</li>
</ul>
<p>In case of failure, the state of the data is unchanged and processing of the input
object can be reattempted. This ensures “exactly-once” processing of each object.</p>
</div>
<div class="section" id="occ-optimistic-concurrency-control">
<h2>OCC: Optimistic Concurrency Control<a class="headerlink" href="#occ-optimistic-concurrency-control" title="Permalink to this headline">🔗</a></h2>
<p>The Cask Data Application Platform uses <a class="reference external" href="http://tephra.incubator.apache.org">Apache Tephra™</a>,
which uses <em>Optimistic Concurrency Control</em> (OCC) to implement transactions. Unlike most relational
databases that use locks to prevent conflicting operations between transactions, under OCC
we allow these conflicting writes to happen. When the transaction is committed, we can
detect whether it has any conflicts: namely, if during the lifetime of the transaction,
another transaction committed a write for one of the same keys that the transaction has
written. In that case, the transaction is aborted and all of its writes are rolled back.</p>
<p>In other words: If two overlapping transactions modify the same row, then the transaction
that commits first will succeed, but the transaction that commits last is rolled back due
to a write conflict.</p>
<p>Optimistic Concurrency Control is lockless and therefore avoids problems such as idle
processes waiting for locks, or even worse, deadlocks. However, it comes at the cost of
rollback in case of write conflicts. We can only achieve high throughput with OCC if the
number of conflicts is small. It is therefore good practice to reduce the probability of
conflicts wherever possible.</p>
<p>Here are some rules to follow for flows, flowlets, and services:</p>
<ul class="simple">
<li>Keep transactions short. The Cask Data Application Platform attempts to delay the beginning of each
transaction as long as possible. For instance, if your flowlet only performs write
operations, but no read operations, then all writes are deferred until the process
method returns. They are then performed and transacted, together with the
removal of the processed object from the input, in a single batch execution.
This minimizes the duration of the transaction.</li>
<li>However, if your flowlet performs a read, then the transaction must
begin at the time of the read. If your flowlet performs long-running
computations after that read, then the transaction runs longer, too,
and the risk of conflicts increases. It is therefore good practice
to perform reads as late in the process method as possible.</li>
<li>There are two ways to perform an increment: As a write operation that
returns nothing, or as a read-write operation that returns the incremented
value. If you perform the read-write operation, then that forces the
transaction to begin, and the chance of conflict increases. Unless you
depend on that return value, you should always perform an increment
only as a write operation.</li>
<li>Use hash-based partitioning for the inputs of highly concurrent flowlets
that perform writes. This helps reduce concurrent writes to the same
key from different instances of the flowlet.</li>
</ul>
<p>Keeping these guidelines in mind will help you write more efficient and faster-performing
code.</p>
</div>
<div class="section" id="using-transactions-in-programs">
<span id="transaction-system-using-in-programs"></span><h2>Using Transactions in Programs<a class="headerlink" href="#using-transactions-in-programs" title="Permalink to this headline">🔗</a></h2>
<p>CDAP provides transactional capabilities to help ensure consistency of data under highly
concurrent workloads. To make transactions easy to use, CDAP will often implicitly execute
application code inside a transaction—and retry the execution if the transaction fails
due to write conflicts.</p>
<p>For example, to guarantee exactly-once processing semantics for flows, the process method
of a flowlet is always run inside a transaction. This transaction encapsulates the removal
of data from an input queue, all data operations performed in the course of processing
this data, and the emitting of data to its output queues for downstream flowlets. All of
these must be together in the same transaction and committed atomically: otherwise,
exactly-once processing cannot be ensured.</p>
<p>For other types of programs, transactions can also be useful. For example, the handler
methods of services are executed transactionally to make sure they operate on consistent
data. The lifecycle methods (<code class="docutils literal notranslate"><span class="pre">initialize()</span></code> and <code class="docutils literal notranslate"><span class="pre">destroy()</span></code>) of all programs are also executed
within an implicit transaction.</p>
<p>However, there are use cases where that transaction is not desired:</p>
<ul class="simple">
<li>The default transaction timeout (as <span class="xref std std-ref">configured by</span> <code class="docutils literal notranslate"><span class="pre">data.tx.timeout</span></code> in <code class="docutils literal notranslate"><span class="pre">cdap-site.xml</span></code>) may be too
short for the operations performed by a method. For example, the <code class="docutils literal notranslate"><span class="pre">destroy()</span></code> method of a
MapReduce program may have to clean up temporary data, or make a web service call to
notify some other party of the job completion.</li>
<li>A method does not perform any transactional operations. For example, FileSet datasets do
not require a transaction—a method using only FileSets therefore does not require an
implicit transaction.</li>
<li>A method performs many operations and wishes to execute them in several short
transactions rather than a single long transaction. A good example of such a method is the
<code class="docutils literal notranslate"><span class="pre">run()</span></code> method of a worker, which runs perpetually and cannot be executed inside a single
transaction. Instead, it needs to start an explicit transaction whenever it performs
operations on transactional datasets.</li>
</ul>
<p>To facilitate these use cases, CDAP offers programs control over the execution of
transactions:</p>
<ul class="simple">
<li>Annotate a method with an <code class="docutils literal notranslate"><span class="pre">&#64;TransactionPolicy</span></code> to turn off the implicit transaction
started by CDAP.</li>
<li>Use the program context’s <code class="docutils literal notranslate"><span class="pre">execute()</span></code> method to run a block of code inside an explicit
transaction.</li>
<li>Control the timeout of transactions by setting a system-wide configuration
(<code class="docutils literal notranslate"><span class="pre">data.tx.timeout</span></code>); by setting a preference for an individual namespace, application, or
program; or by passing a timeout for the transaction to the <code class="docutils literal notranslate"><span class="pre">execute()</span></code> method.</li>
</ul>
<div class="section" id="implicit-versus-explicit-transactions">
<h3>Implicit versus Explicit Transactions<a class="headerlink" href="#implicit-versus-explicit-transactions" title="Permalink to this headline">🔗</a></h3>
<p>By default, CDAP will start an implicit transaction for these methods:</p>
<ul class="simple">
<li>All flowlet process methods</li>
<li>All service handler methods</li>
<li>The <code class="docutils literal notranslate"><span class="pre">ProgramLifecycle</span></code> methods (<code class="docutils literal notranslate"><span class="pre">initialize()</span></code> and <code class="docutils literal notranslate"><span class="pre">destroy()</span></code>) for all types of
programs and sub-programs (flowlets, service handlers, and workflow actions), with the
exception of worker programs.</li>
</ul>
<p>CDAP implicitly starts a transaction for this handler method, and the handler can rely
on the transactional consistency of the data it reads from the dataset.</p>
<p>For MapReduce programs, the lifecycle methods of MapReduce tasks (mappers and reducers)
and MapReduce helpers (such as partitioners and comparators) are always run inside a
transaction: the long-running transaction that encapsulates an entire MapReduce job (see
<a class="reference internal" href="mapreduce-programs.html#mapreduce-transactions"><span class="std std-ref">MapReduce and Transactions</span></a>).</p>
<p>For Spark programs, see <a class="reference internal" href="spark-programs.html#spark-transactions"><span class="std std-ref">Transactions and Spark</span></a> for using
transactions in Spark programs.</p>
<p>For all other lifecycle methods and for service handlers, the implicit transaction can be
turned off by annotating the method with <code class="docutils literal notranslate"><span class="pre">&#64;TransactionPolicy(TransactionControl.EXPLICIT)</span></code>.</p>
<p>This service handler method only accesses FileSets, which do not require transactions.
Therefore, we can safely turn off the implicit transaction for this method.</p>
<p>Note that you can access any dataset through the program context’s <code class="docutils literal notranslate"><span class="pre">getDataset()</span></code> method.
However, if you attempt to perform an operation on a transactional dataset (such as a
Table) without a transaction, that operation will fail with an exception.</p>
<p>For the lifecycle methods of a worker, CDAP does not (by default) start an implicit
transaction. In a similar fashion as above, that can be changed by annotating the
lifecycle method <code class="docutils literal notranslate"><span class="pre">initialize()</span></code>:</p>
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="nd">@Override</span>
<span class="nd">@TransactionPolicy</span><span class="p">(</span><span class="n">TransactionControl</span><span class="p">.</span><span class="na">IMPLICIT</span><span class="p">)</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">WorkerContext</span> <span class="n">context</span><span class="p">)</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="p">{</span>
  <span class="p">...</span>
</pre></div>
</div>
<p>This method will now run inside an implicit transaction.</p>
<p>Note that you cannot annotate the <code class="docutils literal notranslate"><span class="pre">run()</span></code> method of a worker of a custom workflow action
with implicit transaction control; they are always executed without an implicit
transaction and must start transactions explicitly when needed. This is described in the
next section.</p>
</div>
<div class="section" id="explicit-transactions">
<h3>Explicit Transactions<a class="headerlink" href="#explicit-transactions" title="Permalink to this headline">🔗</a></h3>
<p>Every program context (except for the <code class="docutils literal notranslate"><span class="pre">MapReduceTaskContext</span></code>)
allows the executing of a block of code in an explicit transaction.</p>
<p>Be aware that you cannot nest transactions. For example, either:</p>
<ul class="simple">
<li>calling <code class="docutils literal notranslate"><span class="pre">execute()</span></code> from a method that already runs inside an implicit transaction; or</li>
<li>calling <code class="docutils literal notranslate"><span class="pre">execute()</span></code> from the <code class="docutils literal notranslate"><span class="pre">run()</span></code> method of a <code class="docutils literal notranslate"><span class="pre">TxRunnable</span></code></li>
</ul>
<p>would fail with an exception.</p>
</div>
<div class="section" id="controlling-the-transaction-timeout">
<h3>Controlling the Transaction Timeout<a class="headerlink" href="#controlling-the-transaction-timeout" title="Permalink to this headline">🔗</a></h3>
<p>By default, all transactions are executed with the same transaction timeout. This timeout
is <span class="xref std std-ref">configured site-wide</span> as <code class="docutils literal notranslate"><span class="pre">data.tx.timeout</span></code>
(default value 30 seconds) in <code class="docutils literal notranslate"><span class="pre">cdap-site.xml</span></code>. You can change it to a higher number of
seconds if your transactions typically require a longer timeout.</p>
<p>To control the transaction timeout for individual namespaces, applications, or programs,
you can <span class="xref std std-ref">set a preference</span> for the namespace, application, or program.
The name of the preference is <code class="docutils literal notranslate"><span class="pre">system.data.tx.timeout</span></code>.</p>
<p>To configure the timeout for a sub-program (a custom workflow action), prefix
the preference name with <code class="docutils literal notranslate"><span class="pre">action.&lt;name&gt;</span></code>. For example, setting
<code class="docutils literal notranslate"><span class="pre">action.filecheck.system.data.tx.timeout</span></code> to 60 seconds will only affect the action
named <em>filecheck</em> but not the other actions of the workflow.</p>
<p>To control the transaction timeout for an individual run of a program, you can also
provide this setting as a runtime argument when starting the program. Note that this will
<span class="xref std std-ref">prevail over a preference</span> configured for the namespace,
application, or program.</p>
<p>Finally, for explicit transactions, you can control the transaction timeout by passing in
the timeout in seconds to the <code class="docutils literal notranslate"><span class="pre">execute()</span></code> method:</p>
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">getContext</span><span class="p">().</span><span class="na">execute</span><span class="p">(</span><span class="mi">90</span><span class="p">,</span> <span class="k">new</span> <span class="n">TxRunnable</span><span class="p">()</span> <span class="p">{</span>
  <span class="nd">@Override</span>
  <span class="kd">public</span> <span class="kt">void</span> <span class="nf">run</span><span class="p">(</span><span class="n">DatasetContext</span> <span class="n">context</span><span class="p">)</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="p">{</span>
    <span class="p">...</span>
  <span class="p">}</span>
<span class="p">});</span>
</pre></div>
</div>
<p>This will execute the <code class="docutils literal notranslate"><span class="pre">TxRunnable</span></code> in a transaction with a timeout of 90 seconds.</p>
</div>
</div>
<div class="section" id="levels-of-conflict-detection">
<span id="transaction-system-conflict-detection"></span><h2>Levels of Conflict Detection<a class="headerlink" href="#levels-of-conflict-detection" title="Permalink to this headline">🔗</a></h2>
<p>Transactions providing ACID (atomicity, consistency, isolation, and durability) guarantees
are useful in several applications where data accuracy is critical—examples include billing
applications and computing click-through rates.</p>
<p>However, transaction are not for free: the transaction system must track all the writes
made by all transactions, and it must check transactions for conflicts before committing them.
If conflicts are frequent, they will impact performance because the failed transactions
have to be rolled back and reattempted.</p>
<p>In some scenarios, you may want to fine-tune the manner in which a dataset participates in
transactions:</p>
<ul class="simple">
<li>Some applications—such as trending—might not need transactions for all writes, because
small inaccuracies have little effect on trends with great momentum. Applications that
do not strictly require accuracy can trade it for increased throughput by disabling
transactions for some datasets.</li>
<li>Some applications perform concurrent updates to the same row of a table, but typically
those updates do not strictly conflict with each other because they are on different
columns of the row. In this case it can make sense to increase the precision of conflict
detection by tracking changes at the column level instead of the row level.</li>
</ul>
<p>Both of these can be achieved by specifying a conflict detection level when the table is
created. For example, in your application’s <code class="docutils literal notranslate"><span class="pre">configure()</span></code> method:</p>
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">Tables</span><span class="p">.</span><span class="na">createTable</span><span class="p">(</span><span class="n">getConfigurer</span><span class="p">(),</span> <span class="s">&quot;myTable&quot;</span><span class="p">,</span> <span class="n">ConflictDetection</span><span class="p">.</span><span class="na">COLUMN</span><span class="p">);</span>
</pre></div>
</div>
<p>You have these options:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">ConflictDetection.NONE</span></code> to disable transactions for the table. None of the writes
performed on this table will participate in conflict detection. However, all writes
will still be rolled back in case of a transaction failure (the transaction may fail
for other reasons than a conflict on this table).</li>
<li><code class="docutils literal notranslate"><span class="pre">ConflictDetection.ROW</span></code> to track writes at the row level. This means that two
concurrent transactions will cause a conflict if they write to the same row of the table,
even if the writes are for different columns. This is the default.</li>
<li><code class="docutils literal notranslate"><span class="pre">ConflictDetection.COLUMN</span></code> to increase the precision of the conflict detection to
the column level: Two concurrent transactions can write to the same row without conflict,
as long as they write to disjoint sets of columns. This will increase the overhead for
each transaction, because the transaction system must track writes with greater detail.
But it can also greatly reduce the number of transaction conflicts, leading to improved
overall application throughput.</li>
</ul>
</div>
</div>

</div>
    <div class="col-md-2">
      <div id="right-sidebar" class="bs-sidenav scrollable-y" role="complementary">
        <div id="localtoc-scrollspy">
        </div>
      </div>
    </div></div>
</div>
<!-- block main content end -->
<!-- block footer -->
<footer class="footer">
      <div class="container">
        <div class="row">
          <div class="col-md-2 footer-left"><a title="Namespaces" href="namespaces.html" />Previous</a></div>
          <div class="col-md-8 footer-center"><a class="footer-tab-link" href="../table-of-contents/../../reference-manual/licenses/index.html">Copyright</a> &copy; 2014-2020 Cask Data, Inc.&bull; <a class="footer-tab-link" href="//docs.cask.co/cdap/6.1.1/cdap-docs-6.1.1-web.zip" rel="nofollow">Download</a> an archive or
<a class="footer-tab-link" href="//docs.cask.co/cdap">switch the version</a> of the documentation
          </div>
          <div class="col-md-2 footer-right"><a title="Transactional Messaging System" href="transactional-messaging-system.html" />Next</a></div>
        </div>
      </div>
    </footer>
<!-- block footer end -->
<script type="text/javascript" src="../_static/bootstrap-3.3.6/js/bootstrap.min.js"></script><script type="text/javascript" src="../_static/js/bootstrap-sphinx.js"></script><script type="text/javascript" src="../_static/js/abixTreeList-2.js"></script><script type="text/javascript" src="../_static/js/cdap-dynamicscrollspy-4.js"></script><script type="text/javascript" src="../_static/js/cdap-version-menu.js"></script><script type="text/javascript" src="../_static/js/copy-to-clipboard.js"></script><script type="text/javascript" src="../_static/js/jquery.mousewheel.min.js"></script><script type="text/javascript" src="../_static/js/jquery.mCustomScrollbar.js"></script><script type="text/javascript" src="../_static/js/js.cookie.js"></script><script type="text/javascript" src="../_static/js/tabbed-parsed-literal-0.2.js"></script><script type="text/javascript" src="../_static/js/cdap-onload-javascript.js"></script><script type="text/javascript" src="../_static/js/cdap-version-menu.js"></script>
    <script src="https://cdap.gitee.io/docs/cdap/json-versions.js"/></script>
  </body>
</html>